Skip to main content

Internal Transfer

Move funds between two accounts in ledger (same customer/different customers). This API is useful to support internal transfer between two different customer accounts. This is also useful in the fintech context while trying to automate the movement funds between accounts of the same customer.

Method: POST​

{{URL}}/rpc/paymentv2

Example​

Request Parameters
ParameterDescription
methodString
Name of the API method to be invoked. Must be "ledger.ach.transfer"
idString
Unique identifier for the request, used for tracking
paramsObject
payload Object
channelString
Channel through which the transaction is initiated (e.g., "API")
transactionTypeString
Type of transaction. Sample Value : "INTERNAL_TRANSFER"
productString
Product associated with the transfer. Sample Value : "DEFAULT"
programString
Program name associated with the transaction. Sample Value : "DEFAULT"
transactionDateTimeString (DateTime)
Date and time of the transaction in YYYY-MM-DD HH:MM:SS format
referenceString
Unique reference ID for the transaction
reasonString
Reason for the transaction. Sample Value : "Settlement"
transactionAmountObject
amountString (Decimal)
Amount to be transferred. Sample Value : "200"
currencyString
Currency of the transaction amount. Sample Value : "USD"
debtorAccountObject
identificationTypeString
Type of debtor account identifier. Sample Value : "ACCOUNT_NUMBER"
identificationType2
String
Account type
Constant Values : " CHECKING / SAVINGS"
identificationString
Debtor’s Account Number
institutionObject
nameString
Name of the debtor's financial institution. Sample Value : "FINWISE BANK"
identificationTypeString
Type of institution identifier. Sample Value : "ABA"
identificationString
Institution identifier.
Sample Value : "101110802"
creditorAccountObject
identificationTypeString
Type of creditor account identifier. Sample Value : "ACCOUNT_NUMBER"
identificationType2
String
Account type
Constant Values : " CHECKING / SAVINGS"
identificationString
Identifier of the creditor's account
institutionObject
nameString
Name of the Creditor’s financial institution. Sample Value : "CITI BANK"
identificationTypeString
Type of institution identifier. Sample Value : "ABA"
identificationString
Institution identifier.
Sample Value : "101110802"
apiObject
credential
String
Basic (space) [("<Username>:<apiKey>") as Base64 encoded value] to be provided
Sample Value: "Basic bmF2eWEubitlbXBAbmV0eGQuY29tOmY1OWIwY2NlOTU4ZTQ1YTc4MGVhZWIzYWVjOWVjZDAx"
signature
String
Sign the request payload (params.payload) using private key.
Sample Value: "MEQCIAbpxHpdOyBEVlmxPYv7m4Z1OvWJJYw7g7u3GE3T9nmvAiBjKHckSvb1M6O4t7FeWsn2z9Y3dMeYn3HyX/k28ek/Dw=="
apiKey
String
API key is provided at the time of device registration.
Sample Value : "f59b0cce958e45a780eaeb3aec9ecd01"

curl --location '{{URL}}/rpc/paymentv2' \
--header 'Content-Type: application/json' \
--data '{"method":"ledger.ach.transfer","id":"1","params":{"payload":{"program":"100000000045001","product":"PL","channel":"INTERNAL","transactionType":"INTERNAL_TRANSFER","_transactionDateTime":"2021-01-19 06:20:25","reference":"REF100000514","reason":"Settlement","transactionAmount":{"amount":"100","currency":"USD"},"debtorAccount":{"identificationType2":"SAVINGS","identification":"200686362505215","identificationType":"ACCOUNT_NUMBER","institution":{"name":"FINWISE BANK","identification":"011102638","identificationType":"ABA"}},"creditorAccount":{"identification":"200501916028116","identificationType":"ACCOUNT_NUMBER","identificationType2":"SAVINGS","institution":{"name":"FINWISE BANK","identification":"101115399","identificationType":"ABA"}}},"api":{"credential":"Basic cmFqYXJlcEBuZXR4ZC5jb206MDM1Nzg2MmYxYTk4NDc3OGE0ZDU4NGE2YzBjYTMyNzM=","signature":"MEYCIQCY0HxPlIGYG98sz+/l2mZY7oXUcUxZj6aWONfUUk1kGwIhANrOkk3w4nciALAL52XUO+2+JoiXWXnRjuKBp2OBlhgD","apiKey":"0357862f1a984778a4d584a6c0ca3273"}}'



Body​

{
   "method": "ledger.ach.transfer",
   "id": "1",
   "params": {
       "payload": {
           "program": "100000000045001",
           "product": "PL",
           "channel": "INTERNAL",
           "transactionType": "INTERNAL_TRANSFER",
           "_transactionDateTime": "2021-01-19 06:20:25",
           "reference": "REF100000514",
           "reason": "Settlement",
           "transactionAmount": {
               "amount": "100",
               "currency": "USD"
           },
           "debtorAccount": {
               "identificationType2": "SAVINGS",
               "identification": "200686362505215",
               "identificationType": "ACCOUNT_NUMBER",
               "institution": {
                   "name": "FINWISE BANK",
                   "identification": "011102638",
                   "identificationType": "ABA"
               }
           },
           "creditorAccount": {
               "identification": "200501916028116",
               "identificationType": "ACCOUNT_NUMBER",
               "identificationType2": "SAVINGS",
               "institution": {
                   "name": "FINWISE BANK",
                   "identification": "101115399",
                   "identificationType": "ABA"
               }
           }
       },
       "api": {
           "credential": "{{Credential}}",
           "signature": "{{signature}}",
           "apiKey": "{{ApiKey}}"
       }
   }
}

Response: 200​

Response Parameters
ParameterDescription
idString
Unique identifier matching the API request ID
resultObject
apiObject
typeString
Type of API response. Example: "INTERNAL_TRANSFER_ACK"
referenceString
Reference ID of the original transaction
dateTimeString (DateTime)
Date and time of the API response in YYYY-MM-DD HH:MM:SS format
accountObject
accountIdString
Account ID of the account involved in the transaction
balanceCentsInteger
Available balance in cents after the transaction.
holdBalanceCentsInteger
Hold balance in cents
statusString
Status of the account. Example: "ACTIVE"
result.transactionNumberString
Unique identifier for the processed transaction
result.transactionStatusString
Status of the transaction. Example: "COMPLETED"
result.transactionAmountCentsInteger
Transaction amount in cents
result.originalRequestBase64String (Base64 Encoded)
Original request payload in Base64 encoded format
result.processIdString
Internal processing ID assigned to the transaction
headerObject
referenceString
Reference ID echoed from the original request
signature

Mandatory		String
Sign the request payload (params.payload) using private key.
Sample Value: "MEYCIQC29ySJAaiLEPY8+jfTR12p7w6fag2LEzd9ei/4M0UZtgIhAMV3i2XuHWzZ3FkIonlMxnBLBAu9QPiA5c75OkOX0P+O"
apiKey

Optional		String
API key is provided at the time of device registration.
Sample Value : "f59b0cce958e45a780eaeb3aec9ecd01"

{
   "id": "1",
   "result": {
       "api": {
           "type": "INTERNAL_TRANSFER_ACK",
           "reference": "REF100000514",
           "dateTime": "2025-06-04 13:30:13"
       },
       "account": {
           "accountId": "200686362505215",
           "balanceCents": 115384,
           "holdBalanceCents": 600,
           "status": "ACTIVE"
       },
       "transactionNumber": "QA00000003108008",
       "transactionStatus": "COMPLETED",
       "transactionAmountCents": 100,
       "originalRequestBase64": "eyJjaGFubmVsIjoiSU5URVJOQUwiLCJ0cmFuc2FjdGlvblR5cGUiOiJJTlRFUk5BTF9UUkFOU0ZFUiIsInByb2R1Y3QiOiJQTCIsInByb2dyYW0iOiIxMDAwMDAwMDAwNDUwMDEiLCJyZWZlcmVuY2UiOiJSRUYxMDAwMDA1MTQiLCJyZWFzb24iOiJTZXR0bGVtZW50IiwidHJhbnNhY3Rpb25BbW91bnQiOnsiYW1vdW50IjoiMTAwIiwiY3VycmVuY3kiOiJVU0QifSwiZGVidG9yQWNjb3VudCI6eyJpZGVudGlmaWNhdGlvbiI6IjIwMDY4NjM2MjUwNTIxNSIsImlkZW50aWZpY2F0aW9uVHlwZSI6IkFDQ09VTlRfTlVNQkVSIiwiaWRlbnRpZmljYXRpb25UeXBlMiI6IlNBVklOR1MiLCJpbnN0aXR1dGlvbiI6eyJuYW1lIjoiRklOV0lTRSBCQU5LIiwiaWRlbnRpZmljYXRpb24iOiIwMTExMDI2MzgiLCJpZGVudGlmaWNhdGlvblR5cGUiOiJBQkEifX0sImNyZWRpdG9yQWNjb3VudCI6eyJpZGVudGlmaWNhdGlvbiI6IjIwMDUwMTkxNjAyODExNiIsImlkZW50aWZpY2F0aW9uVHlwZSI6IkFDQ09VTlRfTlVNQkVSIiwiaWRlbnRpZmljYXRpb25UeXBlMiI6IlNBVklOR1MiLCJpbnN0aXR1dGlvbiI6eyJuYW1lIjoiRklOV0lTRSBCQU5LIiwiaWRlbnRpZmljYXRpb24iOiIxMDExMTUzOTkiLCJpZGVudGlmaWNhdGlvblR5cGUiOiJBQkEifX19",
       "processId": "PL25060403017008"
   },
   "header": {
       "reference": "REF100000514",
       "apiKey": "0357862f1a984778a4d584a6c0ca3273",
       "signature": "MEYCIQCY0HxPlIGYG98sz+/l2mZY7oXUcUxZj6aWONfUUk1kGwIhANrOkk3w4nciALAL52XUO+2+JoiXWXnRjuKBp2OBlhgD"
   }
}


Error Codes​

Error Codes
Error CodeError Message
A107DUPLICATE_REFERENCE
A112INVALID_AMOUNT
A113INVALID_CHANNEL
A114CUSTOMER_NOT_FOUND
A116INVALID_API_KEY
A118TRANSACTION_REFERENCE_EMPTY
A122PROGRAM NOT FOUND
A123CREDITOR_ACCOUNT_TYPE_EMPTY
A126TRANSACTION_TYPE_EMPTY
A147TRANSACTION NOT FOUND
A157INVALID ACCOUNT NUMBER
A161DEBTOR ACCOUNT NOT FOUND
A166DEBTOR_ACCOUNT_TYPE_EMPTY
A167DEBTOR_ACCOUNT_ID_EMPTY
A169ACCOUNT NUMBER DOES NOT MATCH WITH API KEY
A172IDENTIFICATIONTYPE2 SHOULD BE EITHER SAVINGS OR CHECKING
A183PAYLOAD EMPTY
A184INVALID ORIGINAL TRANSACTION STATUS
A185TRANSACTION ALREADY REVERSED
A186CREDITOR FIRSTNAME REQUIRED
A187CREDITOR POSTAL ADDRESS ADDRESSLINE1 REQUIRED
A188CREDITOR POSTAL ADDRESS ZIPCODE REQUIRED
A189CREDITOR POSTAL ADDRESS COUNTRYCODE REQUIRED
A190CREDITOR CONTACT EITHER PRIMARYEMAIL OR PRIMARYPHONE REQUIRED
A191DEBTOR FIRSTNAME REQUIRED
A192DEBTOR POSTAL ADDRESS ADDRESSLINE1 REQUIRED
A193DEBTOR POSTAL ADDRESS ZIPCODE REQUIRED
A194DEBTOR POSTAL ADDRESS COUNTRYCODE REQUIRED
A195DEBTOR CONTACT EITHER PRIMARYEMAIL OR PRIMARYPHONE REQUIRED
A196DEBTOR USERTYPE REQUIRED
A197DEBTOR IDENTIFICATION REQUIRED
A198DEBTOR IDENTIFICATIONTYPE REQUIRED
A199CREDITOR USERTYPE REQUIRED
A200CREDITOR IDENTIFICATION REQUIRED
A201CREDITOR IDENTIFICATIONTYPE REQUIRED
A205INVALID_PROGRAM
A206INVALID_PRODUCT
A207PRODUCT_PROGRAM_CHANNEL SETTING NOT FOUND
A208ID EMPTY
A209APIKEY NOT FOUND
1111CREDITOR ACCOUNT NOT FOUND
1113CREDITOR NOT FOUND
1116TRANSACTION AMOUNT NOT FOUND
1117TRANSACTION CURRENCY NOT FOUND
1122CREDITOR ACCOUNT IDENTIFICATION TYPE NOT FOUND
1123CREDITOR ACCOUNT IDENTIFICATION TYPE2 NOT FOUND
1126DEBTOR ACCOUNT IDENTIFICATION TYPE NOT FOUND
1127PRODUCT NOT FOUND
1128PROGRAM NOT FOUND
1129CHANNEL NOT FOUND
1130TRANSACTION TYPE NOT FOUND
1131INVALID API KEY
2053INVALID_ACCOUNT_NUMBER
5019INSUFFICIENT BALANCE
9999INTERNAL ERROR
1001CARD HOLDER ALREADY EXISTS
1002INVALID CARDHOLDER FIRST NAME
1003INVALID CARDHOLDER PHONE NUMBER
1004INVALID CARDHOLDER ADDRESS LINE 1
1005INVALID CARDHOLDER CITY
1006INVALID CARDHOLDER STATE
UNAUTHORIZEDAccess Denied
INVALID_SIGNATUREInvalid Signature
NOT_FOUND_USER_DEVICEUser device not found
BAD_CREDENTIALInvalid Credential